
CHAPTER 4 
WORKING WITH 
PROGRAM MODULES 



Tihe creation of a program module is a fairly straightforward process once you have 
folly defined the module interfaces. However, the existence of modules would be of 

3 tie value if you did not have the software tools necessary for manipulation of the 
odules to build your entire program. Three basic tool»arereqaired: 
A linking program that combines many modules into a single module. 

A locating program that assigns absolute memory addresses to a relocatable 
module. 

A library management program that permits you to add modules to a library 

whose contents may be accessed when linking. 

These capabilities are provided by three commands LINK, LOCATE, and LIB; a 
standard object code format; two resident compilers, PLM80 and FORT80; and a 
resident assembler, ASM^. 



NOTE 

The location and linkage features defined in this chapter are not applicable 
to the object code of the 8048 microprocessor. For information about 
MCS-86 object module management, see MCS-86 Software Development 
Utilities Operating Instructions for ISIS-II Users . 



T ie object code format supported by ISIS-II is a relocatable format produced by 
PLM80, FORT80, and ASM80. ISIS-I formats must be converted to the new format 
for use with ISIS-II. See the HEXOBJ and BINOBJ command descriptions in 
C laptcr 3. 

T le LINK program combines files containing object modules of a program into one 
module in one object file, adjusting the relative addresses in the process. When the 
modules to be combined reference each other, you must identify these references as 
public symbols and external symbols thus allowing LINK to satisfy the external 
re Terences of each module. 

Tlie relative addresses assigned to relocatable modules are converted to absolute 
ac dresses by the LOCATE program, which produces an absolute object file (or 
module that can be loaded by ISIS-II for execution, debugging, or memory 
m ipping). 

The LIB program creates and maintains libraries of object modules that can be used 
as building blocks to create new programs via LINK. 

Tlie many reasons for relocating a program and for writing programs in modules are 
di; trussed in the following text. 



Microprocessor Memory Allocation 

The microprocessor memory for any given application is generally not of uniform 
conposition. The memory is usually tailored, with RAM (read-write memory) 
installed for variable data and ROM (read only memory) or PROM (programmable 
rerd only memory) installed for program code. Memory chips can be installed in 
such a way that some addresses have no corresponding physical memory. 
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This diversity in memory design (as well as programming considerations explained 
later) requires you to tailor your program, specifying absolute addresses for the 
actual ROM and RAM locations used for code and data. However, you may not 
knojv the absolute addresses of the ROM or RAM in your final application at the 
time you start to develop the program. At an early stage of development when you 
are testing your program in the system, your only concern with locating the program 
is that it doesn't overlap the resident routines of ISIS-II. The system memory is 
simply a sequence of RAM locations from to 32K, 48K, or 64K. However, as your 
program development continues and debugging becomes a prime concern, address 
requirements are much more specific. Code may be in PROM starting at location 0; 
variable data may begin in the first location of a block of RAM. 

Thelprogram that had a base address of 4000H for compatibility with ISIS-II resi- 
dent software and had variable data immediately following code, may need new 
addresses to meet the requirements of the memory in the final application. In a 
system that deals only with absolute code, you would have to change the source pro- 
gram to specify new addresses and translate again to get object code with correct 
addresses. In the relocation and linkage system of ISIS-II, you simply produce a new 
absolute memory image from the relocatable object modules by using the LOCATE 
program. LOCATE assigns addresses to place code in ROM or PROM, vafMsie 
data, in RAM, and the stack in another area of RAM. 



Pre gram Sef merits 

The LOCATE program allows the user to preassign areas of memory because of the 
way the language translators (PLM80, FORT80, and ASM80} divide a n^mmMt 
object module into segments. The segments are: 

• Code 

• Data 

• Stack 

• Memory 

amed and unnamed common segments (FORT80 only) 



r 



Each segment starts with a relative address of zero. A base address can be specified 
for each segment when it is being LOCATEd. The base address is the actual address 
of the first memory location the segment will occupy. LOCATE adds the base 
addijess to each relative aditeess and adjusts addr^s references accordingly. 



Code Segment 

The code segment is that part of the program destined for ROM because it contains 
machine instructions and program constants that are never modified during execu- 
tion. This segment can also be placed in RAM. In assoKiMy lauagtti^e it consists of 
statetments following a CSEG directive. 



Datja Segment 



The data segment is that part of the program that usually requires RAM. It contains 
variable data and storage for I/O buffers. In asi»mbly language it consists of 
statements following a DSEG directive. 
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S^ack Segment 

The stack segment is for the program stack and must be in RAM. Usually only a 
module that contains a main routine has a reference to a stack segment. Its length is 
d< termined by the compiler for PL/M programs and by the STKLN statement in 
assembly language. Yom can also specify the length when the program is made 
at solute by LOCATE, inferences to the stack segment are made with STACK (a 
re served wovd il assiffll^ IMftiVACKPTR (an idajtifier in PL/M), 



Memory Segment 

The memory segment is assigned to RAM memory that is not allocated to code, 
data, common, or stack segments. References to the memory segment are made with 
MEMORY (a reserved word in assembly language and an identifier in PL/M). 
Although the language translators create a memory segment for each relocatable 
oqject module, its length is unknown until an absolute module is produced by 
LOCATE, which uses the Monitor MEMCK routine and the base address ®f liie 
memory segment to calculate the length of available RAM. 



Common Segments 

The common segments are used for FORT80 named COMMON areas and the 
BLANK COMMON area. Common segments usually contain variables, and 
therefore, are usually placed in RAM. 



Absolute Information 

In addition to the relocatable code, data, stack, common, and memory segments, an 
object module can contain information with absolute addresses already assigned. 
There are three ways this can happen. The ASEG statement in assembly language 
causes statements following it (until a CSEG or DSEG is encountered) to have 
absolute addresses. Absolute modules produced by LOCATE can be linked with 
relocatable modules. PL/M variables declared with the AT attribute produce 
absolute references. 



It is possible to write a self-contained program in assembly language using the ASEG 
statement. This results in an absolute module that can be executed directly after 
assembling because the assembler output is a memory image. This approach is possi- 
bli ! only in cases where relocation is not needed. 



M odular Program D@¥et0|ifnent 

Most programs are too lengthy or too complex to code as a straightline program. 
You can make the job simpler by designing first a main routine that calls separate 
functions in subprograms. The exchange of parameters with these subprograms can 
be determined during the design of the main routine. However, the actual coding of 
the subprograms can be left until later. The final complete program is built from the 
mi tin routine and the subprograms by the LINK program. The advantages of this 
ap E>roach to program design are summarized in the following paragraphs. 
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Papter Program Deveiipnent 

Yotr program can be developed faster if the modular approach is used because 
smsill modules are easier to understand and simpler to program. Breaking a program 
up into functional modules makes it possible to assign the pieces to a team of 
developers. With the specific tasks well defined, you can concentrate on program- 
ming and testing a specific module. You can supply the input required by the module 
and verify it by examining the output. As the modules are debugged, they can be put 
in i library file using the LIB program. When all modules are ready, the LINK pro- 
gran is used to combine the modules into one complete module, which can then be 
assi ped abmksm mmorfwMmm^ UOGkTE. 

Us^ of MWffmM Sotiree Languages 

The modules that make up the final program need not be translated from the same 
language. PL/M, FORTRAN, or assembly language can be used, whichever suits 
the task best. Relocatable modules produced by the compiler, the assembler, or both 
ean|be input to LtNK to build a program. 

Shared Subprograms 

When modules of one program have been tested they can be used by other pro- 
grams. This means that part of the job of future programming is already done. 

Because the module has relocatable addresses, it can be combin^l witii ^fM^ 
programs, having different address requirements each time. 

Ea sier Debugging ami IN'ogram Modification 

It is easier to narrow down the location of a bug when a program is divided into 
modules. When you have identified the module containing the error, you can con- 
centrate on debugging that module. When a program must be modified, it may 
mean that only one or two modules must be changed or added. When the new or 
changed modules have been translated and debugged, a new absolute memory image 
can be created simply by using LINK and LOCATE rather than retranslating the 
entire source program. 



RA^hanics Of Relocation And Linlcage 



LII>!fK is able to combine modules, adjusting relative addresses, and LOCATE is 
able to convert relative addresses to absolute addresses because of information put 
in the object modules by the translators, ASM80, PLM80, and FORT80. The 
following types of information in the object module are used by LINK and 
LOCATE: 

• Relative addresses of instructions and data. 

• A list of address fields in instructions or data that refer to a location in the same 
segment (intra-segment references). 

• A list of address fields in instructions or data that refer to locations in other 
segments in the same module (inter-segment references). 

• A list of address fields in instructions or data that refer to locations not 
contained in the same module (external references). 

• A list of symbols in the module that are declared public or external in the source 
code. 

You should understand external references and declaring symbols public and exter- 
nal to successfully use LINK and LOCATE. However, an understanding of the 
oth<r topics in this section is not as important. It is provided here to give a complete 
pictire of the mechanics of relocation and linkage. 
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iiddressinf 

Th; relative addresses of instructions and data in the code and data segments are 
assigned by ASM80 and PLM80 when a source module is translated. The addresses 
are determined by a location counter starting with zero at the beginning and 
incremented by the number of bytes in each instruction. The address^ mt 
'relative" to the beginning of the segment. 

LINK combines input modules to form one output module by combining all code 
segments into one code segment and all data segments into one data segment. The 
relative addresses of the first segment remain unchanged, but LINK changes the 
relative addresses of the segments that follow to reflect their relationship to the 
beginning of the new segment. In general this means adding the length of the first 
segment to the relative addresses of the second, adding the combined length of th« 
fir^t two segments to the retatfve addresses of the third segment, and so on. 

LOCATE produces an absolute module from a relocatable one by adding the base 
a#iltoess of each segment to each relative address in that segment to get the absolute 
address. The ba$e address of each segment can be specified in the LOCATE com- 
mand or left for LOCATE to i^^. ; 



Intri^efWi^iit i#fer»p^ 

In addition to relocating load addresses, relative addresses contained in instructions 
or data items must be adjusted. If the address refers to a location in the same seg- 
ment, it is called an intrasegment reference. A jump instruction that refers back 
se^ eral instructions to the beginning of a loop is this kind of reference. The value put 
in :he address field by the translator is simply the relative or absolute address of the 
location referred to. If it is a relative address, it is adjusted by LINK when segments 
ar( coifMieii and finalisid If l^^MM by adding the base address of th@ s^ifi^. 



In|tersegment References 

When an address in an instruction refers to a location in another segment of the 
same module, it is called an intersegment reference. An example is an instruction in 
th^ code segment tte reltrs to a variable in the data segment. 

When LINK combines segments to produce a new object module, intersegment 
references are changed tm reflect the new relative addresses of the locations in the 

other segments. 

LOCATE converts the relative address of an intersegment reference to an absolute 
ad lress by adding it to the base address of the segment to which referatce is made. 



Eijternal Ref eftnois and Public Symbols 

When an address field in an instruction refers to a location not contained in the same 
module, it is called an external reference. This reference differs from those above 
be(|ause the translator knows nothing about the relative location of this symbol. 
Therefore, you must declare these symbols external. They then become known as 
external symbols, which means they are defined in other modules. The instructions 
tha t refer to them are external references. 
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The module containing an external reference is said to be an "unsatisfied" module 
(» k said to contain an "unsatisfied" external reference. LINK combines this 
module with the module that contains the proper "connector". This connector is a 
public symbol that matches the external symbol. A public symbol is a symbol 
declared to be public Iq thi iiMgiDNsdule and put in the obj^ oode with il$ wMmm 
by jhe translator. 

When LINK "connects" two modules by matching an external symbol to a public 
symbol, the value of the public symbol (its relative or absolute address) goes in the 
address field of the instruction that refers to it. Then LINK removes the external 
references. It is replaced with an intersegment or intrasegment reference if the public 
syn ibol has a r^&m address. If the public symbol has an absolute address, nothing 
rep the exMM^fertoig ilecause no farther address adjustment is required. 

If the module that LINK produces contains unsatisfied external names. LINK issues 
a wiarning message about each one. This module must be linked again with modules 
corjtaining fiie matehing public symbols in order to produce a satisfied module. The 
unsatisfied external name messages from LINK do not indicate that an error exists. 
In intermediate steps of development before all modules of the program are com- 
plete, you can expect LINK to produce these messages. Also, if you have declared a 
nanie external but never make a reference to it in your program, LINK produces an 
unsi^fied external name m^me mm though no unsatisfied external refei^ttee 
cstlists. 

This points up the fact that you should have some way of identifying the state of the 
objfcct code in a file. Saving the memory maps from a LINK and LOCATE is one 
wai of keeping track; usii^ sus attension in the filename that reflects the type of 
tern s is another way. 

When a module contains no external references, it is said to be "satisfied". The 
public symbols are not removed from the object module because they may be needed 
later if a new module is ttided that has an external reference to one of the public 
syn bols. 

If LOCATE finds an external fetafiBBMje in an object module it is processing, it issues 
a warning message but continues to produce the absolute module. The absolute 
moiiule can be executed, perhaps in debug mode with a breakpoint specified to stop 
pro;essing before the instruction containing the unsatisfied external reference is 
reached. If that instruction is executed, results are unpredictable because the address 
in tl le instruction is undefined. 



Use of Libraries 

Libraries make your job of building programs from object modules via the LINK 
program even easier. The library manager program LIB creates and maintains files 
containing object modules. LIB creates a directory of the modules in each library 
file to keep track of the modules it contains. 

Tht LINK program treats library files in a special way. If you specify a library file as 
input to LINK after specifying the modules to be included, LINK searches the 
library for modules that contain public symbols to match the unresolved external 
references in the preceding modules. If a module from the library is included but it 
also has unresolved external references, LINK searches the library again trying to 
fine the module with the public symbols to satisfy the new external references. This 
process is repeated until a search has been made to satisfy all external references. 
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The library manager program can give you a list of the modules in a library file, 
including the public symbols in each module. You may want to keep all the object 
modules for one program in a library, or you may want to keep modules relating to a 
specific function in one library file. For example, a system library supplied with 
I$]S-II is called SYSTEM. LIS Mmi the obj&A modules for linkifl^i ff^ 

gp smM ISiS-II system routines. 



Link Command 

The ISIS-II program LINK allows you to combine object modules from several 
input files into one object niodafe in output file. In the process of combining 

modules LINK adjusts all addresses so they are relative to the beginning of the 
segments in the output module. LINK also searches libraries for modules that 
refeolve external references in the modules being combined and includes them in the 
output module. If any unresolved external references remain in the.output module, 
L(NK puts a message in the map that describes the structure of the new module. 

The output module must be processed by LOCATE before it can be executed. The 
LOCATE program assigns absolute memory locations to the object module. The 
output module can also be used as input to LINK to be combined witt^ other 
modules into a new and expaniied otftput module. 



The LINK program is called into operation by the LINK command. The syntax of 
th e LMK ^Diwand is: 



LIIitit<iftputlist> TO <outputfile> H^MSiN^) 



' can be either or btMl df IM following two it^s: 
<fileiiaiiie> [«Bi©dloi«ftil(>,<modname2>, . . . ,<modtMllliR^] 

,.,<filenamen>) 



Ir the first item <filename> specifics a file containing object modules or a file con- 
taining a library of object modules. If <filename> is not a library file, it is included 
in the output module. If <filename> is a library file and <modnames> are specified, 

then only the specified modules are linked into the output module. If <modnames> 
are omitted and <filename> is a library, only those library modules that satisfy 
e;<ternal references in modules already named in the <inputlist> or already included 
frbm the library are linked into the output module. In other words, when <mod- 
names> is omitted, only those library modules that satisfy an existing unresolved 
reference are included. 



The second item PUBLICS specifies modules whose absolute public declarations 
only are to be included in the output module. This allows for linking modules 
w thout combining them in the output file so they can be loaded separately. See the 
section on overlays in this chapter for a description of this capability. 

<outputfile> specifies the file to contain the object module resulting from linking 
the input modules. This file must not also be specified in the input list. 

<controls> ammmoi mme kejnwords that control the operation of LINK. The con- 
trols are: 



MAP 



This control requests that a link map be produced. The 

link map is sent to the console output device (:C0:) or to 
the file specified in the PRINT control. The content of the 
link map is described later in this chapter. 
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^ AME(<BMA^Mie>) This control specifies the name to be assigned to the output 
module. The name can be from 1 through 31 characters, 
each of which must be a letter (A through Z), a digit (0 
through 9), a question mark (?), or a commercial at sign 
- (@). However, the first character of the name cannot be be 
a digit. If NAME{modname) is not specified, the name 
part of the output file specification is used as the module 
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I^RINT(<filename>) This control specifies the file to contain the link map. If 
omitted, the link map goes to the console outptf dl^te 
, (:C0:). 



If a LINK command is longer than one line on your console (which must not be 
greater than 122 characters), you can continue it by entering an ampersand (&) as the 
last non-blank character before the carriage return. The ampersand cannot appear 
MMim a fltoWHe or control keyword. H ^ be placed between a k^wm'i m^'^. 
iW(|>ckted 0emm^ list, fox exsmple; 

PRINT& 
(:F1:PRTFIL) 



IS a 



valid use of the continuation character. LINK prompts for the continued line 
wteMl MRMk U Messary, subsequent lines can be continued also. 



LINK uses a temporary file named LINK.TMP on the disk to which the oulput 
is directed. If you have a file by tbia name on the output disk, it wffl tee 
destroyei. 



"Appendix C: Error Messages" lists the LINK error messages. 



Link Map 

The link map produced by LINK includes the following information: 



The LINK sign-on message. 

The command used to call LINK (unless map is output to :C0:). 
The length of the relocatable segments in the output module. 
The addresses of absolute information in the output module. 
The names of the input modules. 
Unresolved external names. 
Non-fatal error messages. 



The following example shows a link map for the output module contained in the file 
SHfP.WRK, which was produced from two modules explicitly listed in the input 
a module included from searching a library to resolve external references, and 



list, 

the public symbols of a fourth module. 
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Tlie REL column in the LINK map specifies the segment relocation type. IM 
f olllowing abbreviations ire used in the REL column: ' , 

byte relocatable 

relocatable 

ii'^^^i filocfttable 

absotaiR«fm©n-reloea^^. 



ISIS-II OBJECT LINKER Vx.y INVOKED BY: 
-LINKFILNAM.EXT,PROG.LIB(TRIG),PROG.LIB,& 
**:|#®t:^i(TANSTA.AFL)'t©'illPl«fW«til« MAP . 



(Non-fatal error messages appear here.) 

LINK MAP OF MODULE GELESTIGATION 
WRITTEN TO WLE :F9:SHtP.WRK 
MODULE fS NOT A MAIN MODULE 

SEGUBNTINFORMATION: 



STIWf 


STOP 


LENGTH 


REL 


NAME 






"mm 


P 


CODE ■ 




10FFH 






CODE 




22FFH 


2H 




CODE 






107H 


B 


DATA 






75H 


B 


/FRED/ 






WF2H 


B 


II 


OOOOH 


0002H 


3H 


A 


ABSOLUTE 


0040H 


071 1H 


6D2H 


A 


ABSOLUTE 


0700H 


07FFH 


100H 


A 


ABSOLUTE 


mmm 


FDW4 


f«- 


A 


ABSraiUTi 



•SAP* 



•OVERLAP* 



INPUT MODULES INCLUDED: 
:FO:FILNAM.EXT (NAVPACK) 
:F0:PROG .LIB (TRIG) 
:F0:PROG .LIB (EXP) 
:FO:TANSTA.AFL (MMW^IPWiyBS) 

UNRESOLVED EXTERNAL NAMES: 

COSIGN— REFERENCED IN :FO:FILNAM.EXT(NAVPACK) 

(Other errors tppesi here.) 



Carder of 



Otflpiit FHe^ 



LINK combines modules from the input list by combining all the code segments 
from the input modules into one code segment, all the data segments into one data 
segment, and all the stack segments into one stack segment. The length of the 
memory segment is computed by LOCATE. Any absolute information in the input 
modules is transferred to the output module with absolute addresses unchanged. If 
ajsolute information is in conflict for the same location, a message to that effect is 
ptit in the link map. 



Worknig With Pre gram Modules 



ISIS-U User's Guide 



The order of combining follows the order in which modules are specified in the input 
list. The first module specified is the first in order in combining. The segments of the 
sec }nd module follow the s^pi(Slfii«f tSie first module at the first available location. 

Exi mple : The M@i«ring i.MI command and explanation shows how modtte mm 
coqibined. 

LINKA.BTOC 

Moldule A contains «ode» data, and stack segments. Module B contains code and .' 
data segment. They are all bylevi^s^ble. The resulting module C tou the follow^ ^ 

ing structure 



CODE 
SEG MENT 



FROM 
MODULE A 



matt 

MOOUIEB 




STACK 
SEGMENT 



MEMORY 
SEGMENT 



FROM 
MODULE A 



LENGTH 
DETERMINED 
BY 



In the process of linking the input modules, external references are satisfied. For 
instuice, if module A has a branch to a point in module B, it is no longer external 
when A and B are combined into C. If A or B has an external reference to a module 
in a library file, the library must be specified in the input list after the module that 
refers to it. Suppose the library file RTNS.LIB coniained a module that satisfied an 
external reference in A. Then the input list could be specified A.RTNS.LIB.B or 
A,G ,RTNS.LIB. "il^p^ibc C: Error Messages" lists the LINK error mmm^. 



Locate Command 



The 



LOCATE program takes an input file containing a relocatable object module 
and produces an output file containing the object module with the relative addresses 
fixed to absolute locations. The LOCATE program is activated by the LOCATE 
command. The syntax of the LOCATE command is: 



-OCATE <inputfUe> [TO <outputfile>] [<controls>] 



wheie 



- Cinputf ile> is tbejoame of the file containing Uie relocatable object cotie. 

<outputfile> is the name of the file that is to contain the absolute object 
module. If TO <outputfile> is omitted, it uses the filename portion of 
<inputfile>. If a file already exists with the same name as specified by 
<outputfile> (or the defaulted name), it is overwritten with the new data. If 
<Coutputfile> is not specified, <inputfile> must consist of a filename and exten- 
sion because the default name for the output file is the filename (without exten- 
sion) from <inputfile>. 
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<controls> specifies one or more tceywords that control the operation of 
LOCATE. The controls and their default values are explained in the following 
descriptions. The LOCATE controls are: 

MAP ■•- ' ■ '^'^ • 

COLUMNS(number) ^"f 
PRlNT(file) 
SYMBOLS 
LINES 
PUBLICS 

PURGE • tt^ 

ORDER(segment sequence) 
CODE(address) 
DATA(a4dress) 

MEMORY(address) i 
/common name/(address) ■ ' 

//(address) Li ■ 

NAME(name) 

RESTiWRTO • ^aSovUT^ 

START(address) 

STACKSIZE(value) 

If la LOCATE command is longer than one line on your console, (which must not be 
gr ;ater than 122 characters), you can continue it by entering an ampersand (&) ss the 
laj t non-blank character before the carriage return. The ampersand cannot appear 
within a filename or control keyword. It can be placed between a keyword and the 
as iociated parameter list, for example: 



m 



LOCATE uses a temporary file named LOCATE. TMP on the disk to which 
the output is directed. If you have a file by this name on the output disk it 

"Appendix C: Error Messages" lists the LOCATE error messages. iji , 

LI3CATE Cont»0l @CNi@fiptions 

MAP 

The MAP control specifies that a memory map be printed on the list device. Nor- 
mally, the printing of the map is suppressed. The map lists the start address for the 
module, the start and step siAresses for each segment along with their len^, mi 
relocatioi^j^fe. 

The map lists the start and stop addresses of the segments and length of each seg- 
ment. The REL column specifies the relocation type. The following abbreviations 
arc used iH fcMlL column: ! 



B byte relocatable 

P page relocatable 

I in-page relocatable 

A absolute or non-relocatable 
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When a segment overlaps another segitt^^t, a warning, (OVERLAP) is printed in the 
map. This does not stop the locate function. This may be intentional, as in the sam- 
ple map. The three byte absolute segment is designated to fit into the data segment. 



The following il l 



: It M&aory map: 



ISIS-II OBJECT LOCATER Vx.y INVOKED BY: 
-LOCATE TRIG.REL MAP PRINT(:CO.) NAME(TRIG) 

MEMORY MAP OF MODULE TRIG 
READ FROM FILE :FO:TRIG.REL 
WRITTEN TO FILE :FO:TRIG 
MODULE START ADDRESS 3000H 



START 


STOP 


LIMITH 


R£L 


NAMl 


mam 


OOOAH 


3H 


A 


ABSOLUTE 


mm 


343FH 


440H 


B 


CODE 


3440H 


mw» 


1»H 


B 


DATA 


3630H 


3632H 


3H 


A 


ABSOLUTE tMEMiili'€WiflMF} 


472FH 


475FH 


31 H 


B 


STACK 


Amm 






a 


MEiioav 



The lenfth of tbe MEMORY segment is always computed to be the amount 
of available memory on the host Intellec development system. If the module 
is executed on the Intellec system, the MEMORY segment length is correct 
as specified. If the module is executed on a different system the actual 
amount of memory depends on the configuration of that system. LOCATE 
of tim-sSa^^mti^mM ^ target systea.. 



CC>LUMNS(nB; 

f*hi: COLUMNS control specifies whether the symbol table in the list file is to be 
pri:ited in 1, 2, or 3 columns. The default is 1. This control is ignored unless SYM- 
iQLS, LINES, or PUBLICS is specified. 



^llIHT(fUe) 

Th; PRINT control specifies a list file for the LOCATE program output. If the 
PRINT control is not specified, the output goes to the console output device (:C0:). 



SYMBOLS 

The SYMBOLS control specifies that a list of local symbols (within a module) and 
input module names is to be included in the symbol table in the list file. Normally, 
the printing of the symbol table is suppressed. Local symbols are listed in the table 
with a type of SYM and module names have the type MOD. 
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VALUE TYPE SYMBOL 





MOD 


TRIG 


301 1H 




SIN' 


301 5H 


SYM 


SIO 


3027H 


SYM 


SI1 


3040H 


SYM 


TRIGEX 


3063H 


PUB 


COS 


3102H 


PtIB 


rm 


3230H 


SYM 


TANO 


3340H 


LIN 


272 



The LINES control specifies that a Hst of the hne numbers and input module names 
fr )m the program is to be included in the symbol table in the list file. Line nujnbars 
hs(ve the type LII^ and ittiiite wiraes have the type MOD. The VALUfi Md is 
blank for module names in the ^MN^ ttA* NefinaUy, tlie printing of the spiiM 
table is suppressed. 



Tie PUBLIC! «Btrol specifies that a list of symbols declared public is to be 
included in the symbol table. Public symbols hiai» lUt ||fg FUS. Normally, the 
pi inting of the symbol table is suppressed . 



PURGE 

Tie PURGE control specifies that line numbers, local symbols, module names, and 
public symbols be removed from the output module. Public symbols could be used, 
if present, to link the absolute module with other modules. Line numbers, local sym- 
bols, and module names could be used for debugging. The PURGE control con- 
denses the size of a module that is completly debugged. This results in saving disk 
loati^HuK. 




ORDER(segment sequence) 

The ORDER control defines the order in which the various segments are assigned 
m emory locations. The list of segments in the segment sequence parameter must be 
separated with spaces . 



If 



ORDER is not specified, the seiments are located in the foiowing order: 

CODE 

STACK 

/commons/ (named and unnamed commons in an arbitrary order) 

DATA 

MEMORY 



This default order can be changed with the ORDER control. LOCATE determiriMI 
the addresses at which the segments reside but it is done in the order specified by the 
c<>ntroL 
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list can be specified in the ORDER control. When a partial list is specified, 
segments specified are located first in the order specified. The remaining 
(QDs [>ecif iol) s^ments follow in the default sequence. For example, the control: 



results in the sequence: DATA, CODE, STACK, /commons/, MEMORY. (Assum- 
ing : 11 segment types exist in the module.) 

The first segment is located 680H bytes above the top of the ISIS-II code (3680H). 
This allows room for 13 input and output buffers (six open files and :C0: and :CI:). 
You can also change the ©fder with the CODE, STACK, /name/, //, DATA, and 
ME140RY controls by specifying a specific address at which each will reside. The 
section "How LOCATE Locates Segments," following the control descriptions 
describes how the default oriil, QHDER con^ol, and specific addrois «»®»P0il- 
intejact to locate segments. • . . 

CODE(address) 
DATA(address) 
STACK(address) 
/common name/(address) 
//(address) 

The segment locations can be specified explicitly with the segment controls. The con- 
trol; are specified with the address. The address can be in decimal, hexadecimal, 
octal, or binary. The address must begin with a digit and may be followed by a ISMr 
ifyng tlie base of number: 

Decimal - D or omitted 
Hexadecimal - H 
Octal - O or Q 
Binary - B 

The specified addresses of some segments may be changed by LOCATE. If because 
of tike addressing within a segment, it must reside at or between 256 byte multiples of 
n^^lffy, Ae I>«»S«te program wil make the adjustment. 

The section "How LOCATE Locates Segments," following the control descriptions 
describes how the default order, ORDER control, and specific address c(MMite 
inte act to locate segments. 



NAME(name) 

The NAME control specifies a name for the output module. The name can be from 1 
through 31 characters, each of which must be a letter (A through Z), a digit (0 
through 9), a question mark (?), or a commercial at sign (@). However, the first 
chaiacter of the name cannot be a digit. If NAME is not specific, the nam« m ^ 
header record of the input file is used. 



RE5TART0 

The RESTARTO control places a jump instruction at locations 0, 1, and 2 in the 
absolute module. The address in the jump instruction is the programs starting 
address (the address of the first instruction to be executed) taken from the input 
mo4ule or from the START control. You would use the RESTARTO control when 
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preparing an absolute module for execution in your prototype system, either the 
sta ndalone syst«fi ©r the systeni beitig emulated with the in-circuit emulator. When 

the RESET signal is input to the CPU, Ihe program counter is set to and execution 
begins with the jump to the beginning of your program. An absolute module 
prepared with the RESTARTO control is not compatible with ISIS-II, which does 
nolt allow user code to be loaded in locations 0, 1, or 2. The RESTARTO control is 
tgi lored if ^ iipit module is n&t t HiaiA wmAnle. 



The START control specifies the address of the first instruction in the code segment 
to be executed. This address overrides the address in the input module. If START is 
on litted, the addr^ is taken ftmn tfe» vstpm. maAute. The STAKf iiwtfot is 
if (he input module is not a main module. 



STACKSIZE(value) 

The STACKSIZE control specifies a value (in bytes) for the size of the stack seg- 
ment. This valwe overrides any cale^Ml meitimumi in tite mput 
module. 

When debugging a program in an Intellec microcomputer development system, 12 
additional bytes of user stack are required beyond that computed by the language 
translator or LIHK. LOCATE adds these 12 bytes if the STACKSIZE parante^ k 
no ; specified. 



How LOCATE Locates Segments 

Module sepnanls sife normally loealei ^quentially in memof y la erier: 

CODE segment 
STACK segment 

/commons/ segments (in an arbitrary order) 

DATA segQtWt I 
MBIfiOW ^-pient I 

You can change the order with an ORDER control and with the CODE, STACK, 
/common/, //, DATA, and MEMORY controls. You can change the order by u$i|i|; 
thi default m4m iai conjunetiofi n«ith tlie ORDER control and the s(|giAmt emffrailt 
sp( eifi^ m msmx. address . 



Locating VtWIftie Oiliult Order 

Wlen you use the default order, the CODE segment is located 680H bytes above the 
top of ISIS-II and the rest of the segments immediately follow in order. Gaps are 
gei^erated only when required by the relocation type of the segment. 

Bytt tti(eeatable (BR) segments are k^ated at the first available hyts. 

Page relocatable (PR) segments are located at the first avaiaUe byte that INSM 
a page boundry (a multiple of 256 (lOOH) bytes). 

In-page relocatable (IP) segments are located at the first available byte such that 
the sqpn^ m totally contaifflgd wMiMn a page. 
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Locating With the Default and ORDER Control 

Yoi| can change the order totally with the ORDER control. When you specify all 
segments in the ORDER control the first segment is located 680H bytes above the 
top of ISIS-II and the rest of the segments immediately follow in the order specified 
in ttie ORDER control. Gaps are generated only when required by the relocation 
type of the segement. 

If you don't specify all the segments in the ORDER control: 

First, the segments specified in the ORDER control are located in the o^der 
sp^ified. ' 

Next, the segments not sporfWrtlB ile ORDER control are lomM I 
following th#|^ segment sp^^d* ^ Mfmk order. 

Gai:>s.are geiMM isily wlien require %iii@.iA«^ioii. type of fte segaenfis.': 

If you submit rtfe f oftowint ^WIH ©pilWl li* the LOCATE comaai^: 

ORDER(DATA STACK) 

the segments will be located in the f oUowini ©rder: 

DATA 
STACK 
CODE 

/commons/ (if FORTRAN) 
MEMORY 



€) 



Locating With the 
anq Specific Addresses 



You can change the order with a combination of the default order, an ORDER con- 
trol, and specific segment location controls. You should not specify a segment in the 
ORDER contr©! witi a segment location control. When all three forms of 
lociiting are ipaients are lo@iMilt^ordjag to tite foiowing: 

• Segments are selected lor pfel»«it in the order specified by the OlttWI 
control and the default sequence as described in the preceding section. 

• The starting address of a segment is either the address following the preceding 
segment (680H above ISIS-II for the first segment) or the address specified in a 
location control. A gap will be generated if required by the relocation type of 
the segment. 

If the LOCATE ewBiand is submitted with tJhe following controls; 
ORDER|»mSf CODKfOWH) 

segments arepfteoii. in Ite'-^sipwiit 

DATA 
STACK 
CODE 
/commons/ 
MEMORY 
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The DATA segment is located 680H bytes above the top of ISIS-U and STACK is 
located immediately following DATA. CODE is located next, but instead of being 

placed immediately following STACK it is placed at address 6000H as specified by 
the CODE control. The /commons/ (if any) immediately follow CODE and 
MEMORY follows the /commons/. In oilier words, the segments are still located in 
the sequence specified by the default order and the ORDER cwtrol bttt the locatioi^ 
are! modified by the individual segment location controls. 



If you are going to locate some segments at specific addresses and let LOCATE 
place the rest, you should use the ORDER control to modify the default sequence so 
that segments are located in an order that corresponds with the specific addresses in 
thej controls. If you aren't careful, conflicts can occur. Be sure to specify the MAP 
control, to verify that segments are placed as intended. Conflicts do not stop the 
LCfCATE function, because there are circumstances where you will want apparent 
coi ifli^sodi m t)m tocation of an a:%^t«ii€ i^p^nt in an internal gipM « si^mmA. 

Wlien you want to locate FORTRAN common segments to specific addresses, you 
sh( uld also locate the MEMORY segment to an address above the top of the highest 
coinmon segment. LOCATE handles the common segments in an arbitrary order, 
will not know ahead of time what order the common segments will be handled 
the command. If the common segment that you place at low memory is the last 
handled by LOCATE, the MEMORY segment will immediately follow it and 
coa^i^ with dl segments above it. 



Yolu 
by 
oni 
wil 



il 



Lli Coniiiiarid 



LIB uses a temporary file named LIB.TMP on the disk to which the output 
is directed. If you have a Me by this name on the output disk it will be 



The ISIS-II LIB program allows you to create specially formatted files to contain 
libraries of object modules, to maintain these libraries by adding and deleting 
moldules, and to obtain a listing of the modules in a library file. Libraries can be 
meA as input to LINK, which may automatically link modules from the library that 
^t: sfy extenMA te^a^ces in the vrnMleB being linked. 

Thi; library manager program is into operation by the LIB command. The 

synjtax of the LIB coramand is:. 

LIB 



operation of LIB is controlled by entering commands to indicate which opera- 
LIB is to perform. LIB prompts for commands with aa aslerisk (*). The com- 



Thi 
tion 

fflands are 



CREATE 

ADD 

DELETE 

LIST 

EXIT 



-If 
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C(>nttnMieii Umes 

If u command to LIB is longer than one line on your console (which must not be 
greater than 122 characters), you can continue it by entering an ampersand (&) as the 
last non-blank character before the carriage return. The ampersand cannot appear 
within a filename or control keyword. It am be p^m&& between a keyword a^d a 
parameter, for example: 

DELETE PVTXIBIt 
(MODI) 



LIB prompts for the continued line with a doulie 



(**). If necessary, subse- 



CREAf i • €r6tto a Library FHd 

Ths CREATE command creates an empty library file. You must use the ADD com- 
maind to add modules to the library file. The &)fstm of the CREATE cooimand m 



QWtM^ <filename> 



where 



<filename> specifies the name to be assigned to the new library file. If a file 

with that name already exists, dLnmw mmmi^ ^B Wg^ W'^ isonsole and LIB 
prompts for another command. 



ADD - Add Modules to a Library File 

The ADD command adds object modules to a library file. The syntax of the ADD 
coptmand i$* 

ADD <filename>[(<modname>,...)] [,...] TO <libfile> 
where 



<filename> can be the name of a library file or the name of a file containing an 
object module. If a library file is specified, all the object modules contained in it 
are added to <Iibfile> unlm <inodiiames> are specified. 

<modnames> can be specified only if <filename> is a library file. Only the 
object modules i^ecified by <niodnames> are added to <libfile>. 



<Iibfile> is the library file being modified by the addition of modules in 
<filename>. 



DELETE - Delete Modules from a Library File 

The DELETE command deletes modules from a library file. The syntax of the 
DELETE &mm&i k: 

DELETE <libfile> (<modname>,...) 

where 

<modname> specifies the object module to be deleted from <libfile>. 
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ST - LM Ulvrary Modules imi l^uMii; 

Tjie LIST command lists the module directory of the library file. The syntax of the 

LlSTcommaaditl; I 



LIST' 



:modna»e>,..4|{,...l ITO <iistfMe>] {FtlMLICSl 



<libfile> is the name of the library file whose entire module directory is to be 
listed unless <modname> is also specific. thato^, aoiy information abo»t 
the specified modules is listed. 

<listfile> is the name of the file to contain the library listing. If omitted, the 
directWf IMni on the currmt «wsi*B ©utpiit device (:COi|. 

PUBLICS specifies that public names in each m#*li|jiiitS l«.lst€d. tt iMS** 
ted, only the module names are listed. 

Tjie format of the listing when public mmm aiSl 
*UST TiST.Llfl PUBLICS 

TEST.LIB 
OPEN 

NOREX 
ABEX 
REDUCE 
HEX 
OCT 
bATUM 
CLOqK 
Tli»l 
LAPSE 
CYC 

.:pilt|tc nafflcai 
module rtaffies 
library name 



EXIT - Return to ISIS-II 

Tlie EXIT command returns control to ISIS-II. When finished with LIB, enter the 
EXIT command, followed by a carriage return. This terminates the LIB program 
and returns coiitrii to ISIS-II, which proapts for a commmmi wWk!&Mfi^am>i*%. 

Example : The following example shows the creation of a library file and the entry 
in the libratp ii tm® modules. The direclofy of the library is listed tefote exiting to 
ISIS-II. 

-LIB 

ISIS-II LIBRARIAN Vx.y 
•CREATE FOO.UB 

•ADD SIN.eWv^.OBJ TO POO.U1 
•LIST FOO.LIB 

SINE 

COSIME 
•EXIT 



'Appendix C: Err« Mewages" lists the LIB error messages. 
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Program Overlays And Linked Loading 

When a program is larger than the available memory space, it is necessary to link 
mod ules without combining ^mn into one module. Thus during execution when 
part 3f the program is no longer needed, another part can be loaded in the same area 
of memory, overlaying the part not needed. Under ISIS-II, programs or parts of 
programs to be loaded separately must be in separate files. The first load can be 
done by entering the name of the file as a command. The subsequent loads are done 
from a p^rogram with the LOAD^xMtt m& or an I/O routine. 

In the typical use of LINK and LOCATE, modules with external references are com- 
bined with modules that have matching public symbols to produce a module with no 
unsatisfied external references. In linking without combining, the external 
references must still be satisfied; that is, they must know the addresses of their mat- 
ching public symbols. Using the keyword PUBLICS before a Mst of modules tells 
LINK that the modules are not to be combined in tlie output moiMit Iwi ilS^^Bly 
to supply the addresses of their public symbols. 

In this way the external references of ai9#idies listed earlier in. the iuimt 
satisfied. For exampte. 

JNK Ki^mufmim to a.^at 

results in a module A.SAT whose external references to symbols contained in B and 
C art satisfied. Howawsr, modules B and C must be absolute modules because LINK 

must know the absolute addresses of the public symbols. Therefore the typical use of 
LINK before LOCATE is reversed. You must LOCATE modules B and C first, 
creating modules with absolute addresses but perhaps with unsatisfied external 
references. The module created in this way can be considered a temporary module 



only to sup^ s^essi^ of pfl^ speiMs needed by other odmM^. 



Consider the following example. A root segment calls segment A and later calls seg- 
ment AA, then segment AAA overlays AA. A diagram of this overlay structure 
Wlsws where the vertical lines indicate a division in time (segments A and B are not 
in memory at the sme time) and the hoi°izaatal lines indicate a division in memory 
spac:. 



AA 
f 


AAA 
f 




B 


A 


mm 
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All the pieces of this overlay structure must be in Separate files because they are 
loaded separately. The root calls A and B; A calls AA and AAA. If you locate the 
root first, you can use the memory map produced by LOCATE to determine the 
base address of A and B. then locate A and B. Use the memory map produced by 

LOCATE for A to determine the base address of AA, AAA. The modules produced 
by LOCATE have absolute memory addresses assigned but external references are 
unsatisfied. These modules cannot be loaded into memory iif -^ettrtlltt bll ^ |« 
used with the PUBLICS keyword in the linking process. 



Suppose the modules produced by LOCATE were given the extension of TMP. Sup- 
pose the root has external references to public symbols in A and B; A has external 
references to public symbols in the root, AA, and AAA; AA and AAA have external 
references to public symbols in A; B has external references to public symbols in the 
root. Then the f#ttowing LIMK cowlBiaftil^ would produce the ssflsfted mn^tllpi 
r^adyt^'Oietrtt^. - 

LINK R00T.TMP,PUBL1CS(A.TMP,B-TMP) TO ROOT 
LINK A.TMP,PUBLICS(ROOT.TMP,AA.TMP.AAA,TMP) TO A 
LINK AA.TMP,POBLICS(A."mP)TO AA 

LINK AAA.TMP,PUBLIGS(A.TMP) TO MA 
LINK B.TMP,PUBLICS(ROOT. TMP) TOB 

Thie modules ROOT, A, AA, AAA, and B are ^bsQluts b!e(:|iu$e of the previous 
L OC ATE Qpsratta and f ttlty satisfied ^smmn of <lSm nXmm. tWK. epeoktim. 
ai e coiHi«et^ bwt not combined . 

To verify that all external references are satisfied in the modules produced by LINK, 
you can LOCATE them again. This time LOCATE should produce no message 
abotiM simMM ©eternal differences. 



When you link without combining to produce overlays, you must provide 
overlay management in the design of your system. That is, before your pro- 
gram makes a reference to an overlay segment, it must make sure that seg- 
ment is in memory. If not, the segment must be read into memory. When a 
segment in memory contains new data that must be saved, it must be written 
out before it is overlaid with another segment. The ability to link without 
combining provides the hooks for an overlay scheme. The runtime manage- 
ment of ov«riid?s must be det^pMsd into your software. 



NIemory Pages and the H ami L Registers 

Relocation types are provided for programs that reference memory by manipulating 
the H and L registers independently. (See the 8080/8085 Assembly Language Pro- 
gtamming Manual 9800^1, for a description of the HIGH and LOW operators.) 
You can store data on a boundary and address elements in it by changing only 
the L register. If the data does not cross a page boundary, you do not have to change 
tlje H register at all. 

However caution most be used if the HIGH operator is used on an arbitrary address 

in relocatable code, you may get an incorrect address because LOCATE assumes the 
unused portion of the address to be zero. If the unused portion of the address is not 
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zerc and the addition of the low order portion of the segment base address causes a 
cany into the high order portion, that carry will not be detected when the HIGH 
operator is used. For example, if HIGH is used on the relocatable address 1234H: . 

HIGH(1234H)= 12H - 
and LOCATE adds a segment base address of lOFOH: 

WITH HIGH OF^i^TOR WITHOUT HIGH OPERATOR 

1200H 1234H _ 

+10F0H +10F0H 

22F0H 2324H 

THE HIGH PART OF THE HIGH PART OF 

WHICH IS 22H WHICH IS 23H 

Because LOCATE has no knowledge of the low order portion of the address there is 
a chance that located HIGH address will be off by one. The located address will be 
correct if there is no carry from the low order portion. 

You can avoid this situation by only using the HIGH operate on ad4x^@is«$ in 
segments that you have defined as page relocatable . 

This circumstance does not exist with the LOW operator. Addresses on which LOW 
peen us^ wil tf«paf s be correct. 

Savings in memory space and execution time can result from this method, but access 
to some areas of memory may be lost because of the way LINK miS i,<©CATE act to 
preserve relocation types. 

When LINK combine se^^ts having diligent relocation types, it follows these 
rule^ 

iyte relocatable segments follow the preceding segment at the next byte. The 
utput segment is byte relocatable only if all input segments are byte 
tdocatable. Otherwise, it is page relocatable. 

rdo^table segments follow the preceding segment at the first available 
page boundary. The bytes from the end of the preceding segment to tiie page 
boundary, if any, are unused. The output segment is page relocatable. 

• Inpage relocatable segments are located at the first location following the 

preceding segment if they fit within the page. Otherwise, they are located at the 
next page boundary and the bytes at the end of the previous page are unused. 
The output segment is inpage relocatable only if it is not more than 256 bytes 
and all input segments are inpage relocatable. Otherwise, the output segment is 
lage relocatable. 

The bytes that are unused in the process of preserving the relocation type of 
segments are flagged in the LINK memory map by the word 'gap.* These gaps are 
unused portions of the program; in a sense they are "lost. 

If LOCATE assigns the base addresses of segments, it does so in a way that 
preserves the relocation type of the segment. It also issues a message if an inpage 
relocatable segment is changed to page relocatable. If you specify a base address for 
a segment with a segment location control that violates the relocation type of the 
segment, LOCATE places the segmoit on the next higher page boundary and. issues 
a message. 
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